Java Engine Properties
This article describes the optional properties that can be placed in your Java Report Engine application's WindwardReports.properties file.
Properties Categories
The below property settings fall into three general categories:
- Read in and set when the Report Engine starts. You need to restart the Report Engine for new values to be read and used. These properties are categorized as Global.
- Read in and used every time a output is generated from a Report Template. When these are changed, the next report will use the new settings. These properties are categorized as Local.
- Default values for properties you can set in a (Process)Report object. When you change these the next instantiation of the report object will use those new values as the defaults. You can then explicitly set these properties in the object. These properties are categorized as Report.
- Other properties that don't fall into the above categories are categorized as Miscellaneous.
Using the WindwardReports.properties File
Usually you will create a WindwardReports.properties file and point to it. To point your project to your WindwardReports.properties, follow these steps:
- Set the location of the WindwardReports.properties file by calling
System.setProperty("WindwardReports.properties.filename", the fully qualified filename);
before calling any Java Report Engine API.
- When Java Report Engine starts, it makes a call to:
System.getProperty("WindwardReports.properties.filename", "WindwardReports.properties");
It then tries to resolve that filename by trying in order:
Thread.currentThread().getContextClassLoader().getResource();
ProcessReport.class.getClassLoader().getResource();
ClassLoader.getSystemResource();
new File();
new URL();
With the resolved resource name from the above steps, it then tries in order:
Thread.currentThread().getContextClassLoader().getResourceAsStream();
ProcessReport.class.getClassLoader().getResourceAsStream();
ClassLoader.getSystemResource().openConnection().getInputStream();
new FileInputStream();
new URL().openConnection().getInputStream();
The properties below can be set as any other Java property.
Global Properties
| Name | Allowed Values | Default | Description |
|---|---|---|---|
| asian.support | true, false | true | If set to false then the server assumes the files needed for output of Asian text is not available and will fall-back to Latin text only |
| default.chart.dpi | any number | 300 | When charts are rendered to a bitmap (for printers), they are rendered at this resolution. |
| default.image.dpi | any number | 96 | If a bitmap does not have it's DPI set, this is the value used. |
| expand.out.text | ignore, newline, paragraph | paragraph | What to do if an Out Tag has a <CR> and/or <TAB> in the text. <TAB> is handled for both newline and paragraph. newline is a line break (like <br/> in html) and paragraph is a paragraph break. |
| font.files | fontname;fontname;… | none | Example: c:/windows/fonts/*.ttf;c:/windows/fonts/*.ttc; A series of paths, separated by semicolons, to where the true type fonts are on the system. The only wildcard recognized is the * (i.e. no regular expressions). The Report Engine will look in the usual directories on Windows and Linux; this setting is just for non-standard locations to also be read in. |
| font.map | font_replace1=font_subst1;… | none | Arial=Courier New;Times New Roman=Verdana Map use of one font to another. In the example above any use of Arial in the generated output will instead use Courier New. Any use of Times New Roman will instead use Verdana. Very useful when a template uses fonts that do not exist on the system the Report Engine is running on. |
| force.bitmap.format | bmp, gif, jpeg, png and tiff | none | This will force all bitmaps in the created report to be converted to the requested format. The default is no conversion. |
| ignore.tag.colors | true, false | false | Set to true to not remove foreground colors from Tags if the color of the Tag in the template matches the Tag's assigned color. |
| layout.document | on, off | on | If set to off, then for output we do not have to layout (DOCX, XLSX, PPTX, HTML in non-pages mode), the engine will not perform layout in the generated output. In this case the ProcessReport.getNumPages() will return an undefined value (usually 0) and any fields in DOCX that depend on page, section, num pages, etc. numbers will be wrong and the fields will need to be updated. The advantage of turning this off is document production will be faster. This setting is ignored for formats we need to layout (PDF, printer, text, etc.) |
| license | a valid Fluent license | none | This is required – it is your license to run the program. It is a uuencoded string and can be in a single line or in multiple lines with each line (except the last one) ending with a "\" (backslash). |
| logging.filename | off, a_log4j_properties_filename | none | The location of your log4j properties file. If you use log4j for your application, put the properties file location here. The value of off means you are not using log4j. There is no need to set this if log4j is initialized before Fluent Reports is called. |
| odata.max-message-size | any number | 10000000 | Set the maximum message size in the OData provider. |
| pdf.font_mapping | auto or postscriptFontname1=displayFontname1;… | none | Can be set to auto or ArialMT=Arial;Arial-BoldMT=Arial,Bold; auto will set the font names to the name specified in the template, overwriting the true postscript name. The series of "postscriptName=FinalName;" is an explicit mapping and you can have as many as you wish. |
| pdf.makeLineToFit | true, false | true | Set to true to force PDF text to fit within its measured (when the Engine determined layout) length. Set to false to have the text take the width Acrobat calculates. |
| pdf.rgbTransparencyBlendingSpace | true, false | false | Set to false to use the RGB space for image color blending in the PDF. |
| system.locale | any locale such as de or de_CH | the system locale | Set the locale for system messages. |
Local Properties
| Name | Allowed Values | Default | Description |
|---|---|---|---|
| check.for.glyphs | on, off | on | Checks the font specified for text and changes the font if it does not have glyphs for some of the text. If a font has normal glyphs, but not bold/italic and those are needed, it will use the normal font and widen/skew the rendered glyphs. |
| check.for.glyphs.fontnames | font name 1;font name 2;… | MS Mincho;Arial Unicode MS | The list of fonts to consider when the specified font does not have the glyphs needed. The font with the largest number of needed glyphs is used. If there is a tie, the earliest one in the list is used. |
| check.for.ole.images | true, false | true | If true the Engine will check all images brought in via an Out Tag for an OLE header (used in Northwind and Access databases) and will strip it off. This has no effect on non-OLE images. |
| data.processor | DataNodeVisitor | No value | If no value is set the Engine will use the legacy Tag Processor. Set to DataNodeVisitor for Tag Processor 2.0. |
| html.embed_images | true, false | false | Set to true to embed images in an HTML output file. Set to false to produce separate image files. |
| html.split_pages | true, false | false | Set to true to produce multiple output files, one html file per document page. Set to false to create one continuous HTML page. |
| html.css-filename | any string | Set to the CSS filename if the CSS file is distinct (note part of the html body. Set to "" if the CSS file is a component in the html body. This is set for both the case of the engine creating a CSS file and for the engine using an existing CSS file. Default is "". | |
| html.css-type | no, include, separate, exists | include | Sets if the css information will be written to a separate file, as part of the html file, or skipped (because the file already exists). Allowed values are: "no" (no css), "include" (write the css contents to the output (html) b file), "separate" (write the css contents to the css stream), & "exists" (assume they have the css file already, 149 * don't write it). The default is "include". |
| line.break | internal, external | internal | Set to internal to use the Engine's internal line breaker. Set to external to use the Java runtime line breaker. The Windows default is external; the default for other operating systems is internal. Use internal for hyphenation, small caps, font scaling, and font spacing for PDF and printer output. |
| report.hyphenate | 0, 1 or 2 | 1 | Control how output is hyphenated: 0 - do not hyphenate; 1 - hyphenate if auto-hyphenate set in template; 2 - hyphenate. |
| report.remove-unused-formats | true, false | false | Set to true to remove unused formats (Word only). |
| report.timeout | any number greater than 0 (seconds) | none | If a report takes longer than this time to generate, it will throw an exception. This is not checked to the second. The Engine checks about every 15 seconds or so to see if it’s passed the timeout. So a timeout of 30 seconds may not throw an exception until 45 seconds. |
| report.trim | none, end.whitespace, and end.blank | none | Set this to trim white space at the end of a report. end.whitespace will remove empty paragraphs and section breaks. end.blank will also remove blank text. |
| report.write-fields-as-fields | true, false | true | If true, DOCX form fields and content controls are written to PDF and HTML reports as form fields. If false, they are written as text. |
| sql.smart-quote | true, false | false | If set to true, a '${var}' will be changed to ? instead of the regular substitution of '?'. |
| sql.timeout | any number 0 or greater (seconds) | Whatever the underlying data connector (JDBC) has as a default. | Set the timeout on SQL selects in the underlying SQL connector. A value of 0 is infinite and is NOT recommended. |
| trim.tables | aggressively | aggressively | For Excel only -- it will remove empty rows at the bottom of the table and empty columns on the right side of rows. It will remove formatted cells, but it will not remove cells with content or that are merged with other cells. |
| txt.font_name | any valid font name | Courier (Courier New on Windows) | Use this font instead of Courier to calculate text placement in the output. |
| txt.font_size | 6 - 256 | 12 | Use this font size instead of 12pt to calculate text placement in the output. |
| use.decimal | true, false | false | Set to true to use BigDecimal instead of Double in the macros. Useful in cases when String to Double rounding errors occur. |
| word.version | 2007, 2010, 2013 or 2016 | 2016 | The template will be parsed using the default values for that version of Word. |
| write.tags | 0, 1, 2 | 2 | When writing Tags to a report (when the data source for a Tag was not applied) it will write the Tags in the following format: 0 - text; 1 - field (Word), Report Designer macro (Excel), text (PowerPoint); 2 - field, bitmap/chart for Tags that produce a bitmap or chart (Word only). |
| report.write-fields-as-fields | true, false | false | When set to false, all form fields and content controls are output as text. When set to true, all form fields and content controls are output unchanged, i.e. they are editable. |
| xml.writer | stax, dom4j | stax (dom4j when running on Android) | Set to dom4j to use dom4j instead of stax to write xml files in generated reports (including the xml inside DOCX, PPT and XLSX files). |
| xpath.default.prefix | any string that’s a valid XML prefix | def | In an XPath query, the namespace with no prefix must have one. Set this to change the value used from def (for default). |
Report Properties
| Name | Allowed Values | Default | Description |
|---|---|---|---|
| base.directory | any string | Set the base directory used for imported filesyss that have a relative path. The default is "". This needs to be a valid rooted full path to a directory. | |
| csv.cell_separator | any string | , | In CSV reports, changes the separator between cells from "," to the specified string. |
| csv.quote_char | any string | " | In CSV reports, changes the quote delimiter from " to this string. |
| csv.newline | any string | \r\n | In CSV reports, changes the new line string from \r\n (carriage return, line feed) to this string. |
| csv.trim_whitespace | true, false | false | In CSV reports, if set to true, all white space at the end of the cell contents in all cells will be trimmed. |
| date.format.mode | default, legacy | default | Determines the date format parsing style. Legacy is the date formatting used prior to version 21.*. Default is the new date formatting introduced version 21. |
| html.full_file | true, false | true | The default value for ProcessOpenXmlAPI.getFullFile(). This can be overridden with a programmatic call to ProcessReport.setFullFile(). |
| html.html_type | see setSpec() | see setSpec() | The default value for ProcessOpenXmlAPI.getSpec().This can be overridden with a programmatic call to ProcessReport.setSpec(). |
| pdf.compression_level | 0, 1 or 2 | 1 | The default value for ProcessPdf.getCompressionLevel().This can be overridden with a programmatic call to ProcessPdf.setCompressionLevel(). |
| pdf.font_level | 0, 1 or 2 | 1 | The default value for ProcessPdf.getCompressionLevel().This can be overridden with a programmatic call to ProcessPdf.setCompressionLevel(). |
| pdf.key_length | 40 or 128 | 40 | The default value for ProcessPdf.getKeyLength().This can be overridden with a programmatic call to ProcessPdf.setKeyLength(). |
| pdf.owner_password | any string | none | The default value for ProcessPdf.getOwnerPassword().This can be overridden with a programmatic call to ProcessPdf.setOwnerPassword(). |
| pdf.PDF_A | on, off | off | Enables PDF_A3b. The default value for ReportPdf.isPdfA(). This can be overridden with a programmatic call to ReportPdf.setPdfA(). |
| pdf.security | see getSecurity() | 0 | The default value for ProcessPdf.getSecurity().This can be overridden with a programmatic call to ProcessPdf.setSecurity(). |
| pdf.user_password | any string | none | The default value for ProcessPdf.getUserPassword().This can be overridden with a programmatic call to ProcessPdf.setUserPassword(). |
| report.hidden.mode | see ProcessReport.setHiddenMode() | 0 | The default for ProcessReport.getHiddenMode(). This can be overridden with a programmatic call to ProcessReport.setHiddenMode(). |
| report.locale | any locale string (e.g. en_US) | the system locale | The default value for ProcessReport.setLocale(). You must use either a language (en) or language/country (en_US). This can be overridden with a programmatic call to ProcessReport.setLocale(). This is the locale used to process output like the default formatting of a currency amount. |
| report.locale_asian | any locale string (e.g. en_US) | the system locale for East Asian content | Similar to report.locale except used when content for a Tag is marked as East Asian. |
| report.locale_bidi | any locale string (e.g. ar_SA) | the system locale for bidi content | Similar to report.locale except used when content for a tag is marked as bi-directional. |
| txt.break_page | true, false | false | The default value for ProcessText.getBreakPage(). This can be overridden with a programmatic call to ProcessPdf.setBreakPage(). |
| txt.show_headers | true, false | false | The default value for ProcessText.getUseMargins(). This can be overridden with a programmatic call to ProcessPdf.setUseMargins(). |
| txt.use_margins | true, false | false | The default value for ProcessText.getUseMargins(). This can be overridden with a programmatic call to ProcessPdf.setUseMargins(). |
| txt.use_soft_eoln | true, false | false | The default value for ProcessText.getUseSoftEoln(). This can be overridden with a programmatic call to ProcessPdf.setUseSoftEoln(). |
| use.embedded-fonts | true, false | false | When set to true, fonts embedded in docx templates will be used to generate PDF output. Disclaimer - Users are responsible for knowing if the fonts embedded in the template can be used and distributed this way. |
| skip.itext.license | true, false | false | When set to true, the iText license will not be set. This is used if you have an itext license set already in you application. |
| printer.mode | default, legacy | default | Determines which printer mode to use. "Default" is the default printer mode which was introduced in version 24.0. "Legacy" is the printer mode used in versions prior to 24.0. This property was introduced in version 24.2.0. |
| pdf.includeHeaderFooterOnPdfImport | true, false | true | Set to false to prevent headers and footers from the parent docx being copied on top of imported pdf |
| openxml.copy-drawings | true, false | true | Set to "true" if drawings are to be copied to output, set to "false" to drop them. Drawings are only copied for DOCX -> DOCX, PPTX -> PPTX (soon), and XLSX -> XLSX. Default is "true". |
| openxml.copy-metadata | no-datasource | no, no-datasource, yes | Set if the Fluent metadata will be copied to the generated report. This can only occur if the template and generated report are both the same type of OpenXML files. Allowed values are "no" (don't copy), "no-datasource" (copy if no datasources are applied), & "yes" (copy it). Default is "no-datasource". |
| openxml.copy-shapes | true, false | true | Set to "true" if shapes are to be copied to output, set to "false" to drop them. Shapes are only copied for DOCX -> DOCX, PPTX -> PPTX (soon), and XLSX -> XLSX. Default is "true". |
| openxml.recalculate | true, false | false | Set to "true" if the generated document is to perform recalculation when first opened. Presently only implemented for DOCX and XLSX. Default is "false". |
Miscellaneous Properties
| Name | Allowed Values | Default | Description |
|---|---|---|---|
| import.use.child.styles | true, false | true | (This property pertains to version 13.x; for applying/importing parent styles in versions 14.x and later, see the Import Tag Reference.) This is only used if an Import Tag does not have this property set. When an imported template's style settings don't match the master document this determines if default settings in the imported document will match the imported style (true) or the master style (false). |
| sql.parameters | substitution, parameters and parameters.always | parameters | Sets the default value in DataSourceProvider.setParamMode(). |
| use.parent.format | true, false | false | (Version 13.x only. For applying/importing parent styles in versions 14.x and later, see the Import Tag Reference). This sets the default value for the Import Tag use-parent-format property. The default is false and does nothing. If set to true, then imported templates will have their first paragraph and character formatting set to that of the paragraph in the parent template where the Import Tag is located. |
| proxy.authentication | username;password | none | This value allows for Authentication Credentials to be passed into the engine for use with a configured Proxy. For more details on using a proxy, see Java RESTful Engine Proxy Configuration? |